docs/development/Windows 11 - VS Code - WSL2 - Hardware Debugging.md

   1 # Environment prerequistes
   2 - Windows 10/11
   3 - WSL2 (Ubuntu 20.04), [how to install WSL2](https://docs.microsoft.com/en-us/windows/wsl/install)
   4   - **ATTENTION:** Works ONLY on WSL2 Kernel version 5.10.60.1 or later, check it with command `uname -a` and if it is lower - update WSL2
   5     - Using Windows Update: Start > Settings > Windows Update > Advanced Options > Receive updates for other Microsoft products SHOULD be Turned ON
   6       - Start > Settings > Windows Update > Check for updates
   7     - Using Elevated Command Prompt: wsl --update
   8     - NOTE: If your WSL is V1 -> Switch it to V2 or install new WSL (Ubuntu 20.04) instance (switching are done with command `wsl --set-default-version 2`)
   9 - ST-Link V2 Debugger
  10 - INAV Project are Cloned from GitHub to WSL2 storage space, look at:
  11   - [IDE - Visual Studio Code with Windows 10](https://github.com/iNavFlight/inav/blob/master/docs/development/IDE%20-%20Visual%20Studio%20Code%20with%20Windows%2010.md)
  12   - [Building in Windows 10 or 11 with Linux Subsystem](https://github.com/iNavFlight/inav/blob/master/docs/development/Building%20in%20Windows%2010%20or%2011%20with%20Linux%20Subsystem.md)
  13   - [Hardware Debugging](https://github.com/iNavFlight/inav/blob/master/docs/development/Hardware%20Debugging.md)
  14
  15 # Installation
  16 ## WSL2 Setup
  17 ### Install prerequistes
  18 - `sudo apt install linux-tools-5.4.0-77-generic hwdata`
  19 - `sudo update-alternatives --install /usr/local/bin/usbip usbip /usr/lib/linux-tools/5.4.0-77-generic/usbip 20`
  20 - `sudo apt install libncurses5`
  21 ### Adjust rules to allow connecting with non-root
  22 The following script creates access rules for ST-LINK V2, V2.1 and V3 and for some USB-to-serial converters, download it to new file under you home folder, save, change attributes and run
  23 - `nano createrules.sh`
  24 - Copy and Paste script below
  25 - Ctrl-X
  26 - Y
  27 - Enter
  28 - `sudo chmod +x createrules.sh`
  29 - `./createrules.sh`
  30 ```
  31 #!/bin/bash
  32
  33 sudo tee /etc/udev/rules.d/70-st-link.rules > /dev/null <<'EOF'
  34 # ST-LINK V2
  35 SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", MODE="600", TAG+="uaccess", SYMLINK+="stlinkv2_%n"
  36
  37 # ST-LINK V2.1
  38 SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE="600", TAG+="uaccess", SYMLINK+="stlinkv2-1_%n"
  39 SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3752", MODE="600", TAG+="uaccess", SYMLINK+="stlinkv2-1_%n"
  40
  41 # ST-LINK V3
  42 SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374d", MODE="600", TAG+="uaccess", SYMLINK+="stlinkv3loader_%n"
  43 SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374e", MODE="600", TAG+="uaccess", SYMLINK+="stlinkv3_%n"
  44 SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374f", MODE="600", TAG+="uaccess", SYMLINK+="stlinkv3_%n"
  45 SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3753", MODE="600", TAG+="uaccess", SYMLINK+="stlinkv3_%n"
  46 EOF
  47
  48 sudo tee /etc/udev/rules.d/70-usb-to-serial.rules > /dev/null <<'EOF'
  49 # CP2101 - CP 2104
  50 SUBSYSTEMS=="usb", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", MODE="600", TAG+="uaccess", SYMLINK+="usb2ser_%n"
  51
  52 # ATEN UC-232A
  53 SUBSYSTEMS=="usb", ATTRS{idVendor}=="0557", ATTRS{idProduct}=="2008", MODE="600", TAG+="uaccess", SYMLINK+="usb2ser_aten_%n"
  54 EOF
  55
  56 sudo udevadm control --reload-rules
  57 ```
  58 #### In case you want reload services manually later
  59 - `sudo service udev restart`
  60 - `udevadm control --reload`
  61
  62 ## Windows Setup
  63 - Download last usbipd from [here](https://github.com/dorssel/usbipd-win/releases)
  64 - Install it
  65
  66 ## VS Code Setup
  67 - INAV project is on WSL drive
  68 - Folder opened using WSL Remote extension
  69 - Cortex Debug extension installed
  70 - CMake will install all dependencies after first build automatically
  71 - Use configuration files provided below, place them to `.vscode` subfolder (create it if required)
  72
  73 # Debugging
  74 ## Preparing for debugging (before each new debug session)
  75 ### Open WSL2 prompt
  76 - Go to project folder
  77 - `lsusb`
  78 - `sudo /lib/systemd/systemd-udevd --daemon`
  79 - `sudo udevadm control --reload-rules && udevadm trigger`
  80 - REPLUG USB
  81 ### Open Elevated Command Prompt (Run as Administrator)
  82 - `usbipd wsl list` - shows you plugged and accessible USB devices
  83 - `usbipd wsl attach --busid ID_OF_DEVICE_FROM_FIRST_COMMAND` - will attach USB device to WSL
  84 - Just for info: `usbipd detach --busid ID_OF_DEVICE_FROM_FIRST_COMMAND` - will deattach USB device from WSL
  85 ### Back to WSL2 prompt
  86 - `lsusb` - should show you just attached USB device
  87 - `st-info --probe` - should "see" ST-Link and MCU
  88
  89 #### Leave Command Prompt and WSL Prompt minimized (for later usage)
  90 #### **NOTE:** Due to some USB reconnect issues, sometimes, is need to execute `usbipd wsl list` and `usbipd wsl attach...` commands again, to reconnect ST-Link to WSL
  91
  92 ## Debugging
  93 - Connect SWD from ST-Link to FC board (at least GND, SWDIO and SWCLK should be connected, but connecting Vref to +3.3V pad and RESET accordingly will improve debugging stability a lot!)
  94 - Power FC (can be powered from USB)
  95 - Select (Debug) CMake configuration
  96 - Build required target from VSCode
  97 - Use VS Code Run -> Start Debugging (F5) menu (make sure debugging target is "Cortex Debug")
  98
  99 **NOTE:** sometimes "autobuild" script is not performed well, it is recommended to repeat last two steps every time you change code and need "reflash-debug"
 100
 101 **NOTE:** after long and/or intensive debugging OpenOCD can crash, in this case just reopen VSCode, replug ST-Link USB, reattach USB to WSL and start debug session again
 102
 103 # Troubleshooting
 104 - OpenOCD shows Permission denied during "Flashing":
 105   - Go to WSL, INAV Project folder and run `cd src/utils` and `sudo chmod +x *`
 106 - If running from WSL itself and get errors:
 107   - Go to WSL and run
 108     - `sudo apt install gdb-multiarch`
 109     - `sudo ln -s /usr/bin/gdb-multiarch /usr/bin/arm-none-eabi-gdb`
 110
 111 # References
 112 - https://github.com/dorssel/usbipd-win/wiki/WSL-support
 113 - https://devblogs.microsoft.com/commandline/connecting-usb-devices-to-wsl/#:~:text=Select%20the%20bus%20ID%20of,to%20run%20a%20sudo%20command.&text=From%20within%20WSL%2C%20run%20lsusb,it%20using%20normal%20Linux%20tools.
 114 - https://calinradoni.github.io/pages/200616-non-root-access-usb.html
 115
 116 # VS Code Example configurations
 117 `launch.json`
 118 ```
 119 {
 120     // Use IntelliSense to learn about possible attributes.
 121     // Hover to view descriptions of existing attributes.
 122     // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
 123
 124     // ******* INAV ********
 125     // Define the following values in settings.json
 126     //      - BUILD_DIR: Relative path to the build directory
 127     //      - TARGET: Target name that you want to launch
 128
 129     "version": "0.2.0",
 130     "configurations": [
 131         {
 132             "name": "Cortex Debug",
 133             "cwd": "${workspaceRoot}",
 134             "executable": "${config:BUILD_DIR}/bin/${config:TARGET}.elf",
 135             "request": "launch",
 136             "type": "cortex-debug",
 137             "servertype": "openocd",
 138             "device": "${config:TARGET}",
 139             "configFiles": [
 140                 "${config:BUILD_DIR}/openocd/${config:TARGET}.cfg"
 141             ],
 142             "preLaunchTask": "openocd-debug-prepare",
 143             "svdFile": "${config:BUILD_DIR}/svd/${config:TARGET}.svd",
 144         }
 145     ]
 146 }
 147 ```
 148
 149 `settings.json`
 150 ```
 151 {
 152     "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools",
 153     "files.associations": {
 154         "general_settings.h": "c",
 155         "parameter_group.h": "c"
 156     },
 157     "BUILD_DIR": "build",
 158     "TARGET": "MAMBAF405"
 159 }
 160 ```
 161
 162 `tasks.json`
 163 ```
 164 {
 165     // See https://go.microsoft.com/fwlink/?LinkId=733558
 166     // for the documentation about the tasks.json format
 167     "version": "2.0.0",
 168     "options": {
 169         "env": {
 170             "TARGET": "${config:TARGET}",
 171         }
 172     },
 173     "tasks": [
 174         {
 175             "label": "target",
 176             "type": "shell",
 177             "command": "make", "args": ["-C", "${config:BUILD_DIR}", "${config:TARGET}"],
 178             "problemMatcher": "$gcc",
 179             "group": {
 180                 "kind": "build",
 181                 "isDefault": true
 182             },
 183             "presentation": {
 184                 "echo": true,
 185                 "reveal": "always",
 186                 "focus": false,
 187             }
 188         },
 189         {
 190             "label": "flash",
 191             "type": "shell",
 192             "command": "make", "args":  ["-C", "${config:BUILD_DIR}", "openocd_flash_${config:TARGET}"],
 193             "dependsOn": "elf"
 194         },
 195         {
 196             "label": "svd",
 197             "type": "shell",
 198             "command": "make", "args":  ["-C", "${config:BUILD_DIR}", "svd_${config:TARGET}"],
 199             "problemMatcher": []
 200         },
 201         {
 202             "label": "openocd-cfg",
 203             "type": "shell",
 204             "command": "make", "args":  ["-C", "${config:BUILD_DIR}", "openocd_cfg_${config:TARGET}"],
 205             "problemMatcher": []
 206         },
 207         {
 208             "label": "openocd-debug-prepare",
 209             "type": "shell",
 210 //            "dependsOn": ["svd", "openocd-cfg", "flash"],
 211             "dependsOn": ["svd", "openocd-cfg"],
 212             "problemMatcher": []
 213         }
 214     ]
 215 }
 216 ```
 217
 218 `cpp_properties.json`
 219 ```
 220 {
 221     "configurations": [
 222         {
 223             "name": "Win32",
 224             "includePath": [
 225                 "${workspaceRoot}",
 226                 "${workspaceRoot}/src/main/**"
 227             ],
 228             "browse": {
 229                 "limitSymbolsToIncludedHeaders": false,
 230                 "path": [
 231                     "${workspaceRoot}/**"
 232                 ]
 233             },
 234             "intelliSenseMode": "msvc-x64",
 235             "cStandard": "c11",
 236             "cppStandard": "c++17",
 237             "defines": [
 238                 "USE_OSD",
 239                 "USE_GYRO_NOTCH_1",
 240                 "USE_GYRO_NOTCH_2",
 241                 "USE_DTERM_NOTCH",
 242                 "USE_ACC_NOTCH",
 243                 "USE_GYRO_BIQUAD_RC_FIR2",
 244                 "USE_D_BOOST",
 245                 "USE_SERIALSHOT",
 246                 "USE_ANTIGRAVITY",
 247                 "USE_ASYNC_GYRO_PROCESSING",
 248                 "USE_RPM_FILTER",
 249                 "USE_GLOBAL_FUNCTIONS",
 250                 "USE_DYNAMIC_FILTERS",
 251                 "USE_DSHOT",
 252                 "FLASH_SIZE 480",
 253                 "USE_I2C_IO_EXPANDER",
 254                 "USE_PCF8574",
 255                 "USE_ESC_SENSOR"
 256             ],
 257             "configurationProvider": "ms-vscode.cmake-tools"
 258         }
 259     ],
 260     "version": 4
 261 }
 262 ```